home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat2 / standard / sprofil.z / sprofil
Text File  |  1998-10-20  |  9KB  |  198 lines
  1.  
  2.  
  3.  
  4. SSSSPPPPRRRROOOOFFFFIIIILLLL((((2222))))                                                          SSSSPPPPRRRROOOOFFFFIIIILLLL((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      sprofil - execution time profile for disjoint text spaces
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ttttiiiimmmmeeee....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////pppprrrrooooffffiiiillll....hhhh>>>>
  14.      iiiinnnntttt sssspppprrrrooooffffiiiillll((((ssssttttrrrruuuucccctttt pppprrrrooooffff ****pppprrrrooooffffpppp,,,, iiiinnnntttt pppprrrrooooffffccccnnnntttt,,,,
  15.                  ssssttttrrrruuuucccctttt ttttiiiimmmmeeeevvvvaaaallll ****ttttvvvvpppp,,,, uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt ffffllllaaaaggggssss))));;;;
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      sssspppprrrrooooffffiiiillll provides CPU-use statistics by profiling the amount of CPU time
  19.      expended by a program in disjoint text spaces.  This is useful if you
  20.      need to profile programs using shared libraries or profile an address
  21.      space using different granularities for different sections of text.
  22.      sssspppprrrrooooffffiiiillll generates the statistics by creating an execution histogram for a
  23.      current process.  The histogram is defined for a list of regions of
  24.      program code to be profiled specified by members of the _p_r_o_f_p array:
  25.      profp[0], profp[1], ..., profp[profcnt-1].
  26.  
  27.      The _p_r_o_f structure is defined as
  28.      struct prof {
  29.              void     *pr_base;    /* buffer base */
  30.              unsigned pr_size;     /* buffer size */
  31.              __psunsigned_t pr_off;     /* pc offset */
  32.              unsigned pr_scale;    /* pc scaling */
  33.      };
  34.  
  35.      Each _p_r_o_f entry specifies a region of text space that needs to be
  36.      profiled, and the fields of the structure take on the same meaning as the
  37.      arguments of the pppprrrrooooffffiiiillll((((2222)))) system call.
  38.  
  39.      _p_r__b_a_s_e is a buffer of _p_r__s_i_z_e bytes in which the histogram counts are
  40.      stored.
  41.  
  42.      _p_r__o_f_f , _p_r__s_c_a_l_e , and _p_r__s_i_z_e specify the region to be profiled.
  43.  
  44.      _p_r__o_f_f is effectively the start address of the region to be profiled.
  45.  
  46.      If non-NULL, _t_v_p points to a _s_t_r_u_c_t _t_i_m_e_v_a_l which on return will contain
  47.      the time value corresponding to one clock tick.
  48.  
  49.      Valid _f_l_a_g_s values include PPPPRRRROOOOFFFF____UUUUSSSSHHHHOOOORRRRTTTT and PPPPRRRROOOOFFFF____UUUUIIIINNNNTTTT, which result in the
  50.      _p_r__b_a_s_e field of each _p_r_o_f entry being treated as a pointer to an array
  51.      of _u_n_s_i_g_n_e_d _s_h_o_r_t or _u_n_s_i_g_n_e_d _i_n_t, respectively.  You achieve a 1-1
  52.      mapping of instructions to counters for PPPPRRRROOOOFFFF____UUUUSSSSHHHHOOOORRRRTTTT and a _p_r__s_c_a_l_e of
  53.      0x8000, or PPPPRRRROOOOFFFF____UUUUIIIINNNNTTTT and a _p_r__s_c_a_l_e of 0x10000.  Note that a 1-1 mapping
  54.      of PPPPRRRROOOOFFFF____UUUUIIIINNNNTTTT counters consumes twice as much space as for PPPPRRRROOOOFFFF____UUUUSSSSHHHHOOOORRRRTTTT
  55.      counters, and should only be used in those cases where you expect a 16-
  56.      bit counter to overflow.
  57.  
  58.  
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. SSSSPPPPRRRROOOOFFFFIIIILLLL((((2222))))                                                          SSSSPPPPRRRROOOOFFFFIIIILLLL((((2222))))
  70.  
  71.  
  72.  
  73.      Callers may also specify PPPPRRRROOOOFFFF____FFFFAAAASSSSTTTT in the _f_l_a_g_s field. This value will
  74.      provide more accurate profiling by forcing the system to take samples
  75.      once every millisecond. Fast profiling requests can reduce system
  76.      performance noticably. The tuneable system parameter rrrreeeessssttttrrrriiiicccctttt____ffffaaaassssttttpppprrrrooooffff
  77.      can be used to disable this feature.
  78.  
  79.      If overlapping text regions are specified, then the _p_r__b_a_s_e associated
  80.      with the largest offset less than the value of the program counter(PC)
  81.      gets incremented.  If more than one text region has the same offset, the
  82.      first one is chosen.
  83.  
  84.      A text region with the _p_r__o_f_f of 0 and _p_r__s_c_a_l_e of 0x0002 will act as an
  85.      overflow bin. Any PC value not previously matched or outside the regions
  86.      of text space specified is considered to match this text region and the
  87.      first counter of the specified _p_r__b_a_s_e is incremented. If specified, such
  88.      an overflow bin should always be last in the list of specified regions.
  89.  
  90.      sssspppprrrrooooffffiiiillll can fail with:
  91.  
  92.      [E2BIG]      _p_r_o_f_c_n_t was less than or equal to 0, or greater than
  93.                   PPPPRRRROOOOFFFFIIIILLLL____MMMMAAAAXXXX....
  94.  
  95.      [EFAULT]     Either _p_r_o_f_p or _t_v_p points to an illegal address.
  96.  
  97.      [EINVAL]     The overflow bin is not last in the list of specified
  98.                   regions, or _f_l_a_g_s does not contain one of the values
  99.                   (PPPPRRRROOOOFFFF____UUUUSSSSHHHHOOOORRRRTTTT or PPPPRRRROOOOFFFF____UUUUIIIINNNNTTTT).
  100.  
  101.      [EACCES]     The _f_l_a_g_s field specified PPPPRRRROOOOFFFF____FFFFAAAASSSSTTTT but the feature has been
  102.                   disabled using the rrrreeeessssttttrrrriiiicccctttt____ffffaaaassssttttpppprrrrooooffff tuneable system
  103.                   parameter or the hardware does not support fast clock ticks.
  104.  
  105. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  106.      If successful, sssspppprrrrooooffffiiiillll returns 0. Otherwise, a -1 is returned and the
  107.      global variable eeeerrrrrrrrnnnnoooo is set to indicate the error.
  108.  
  109. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  110.      profil(2), prof(1), times(2), monitor(3X), intro(2).
  111.  
  112. NNNNOOOOTTTTEEEESSSS
  113.      Each call to sssspppprrrrooooffffiiiillll will disable any profiling enabled by previous
  114.      sssspppprrrrooooffffiiiillll calls.  Profiling is not enabled for a given text region if the
  115.      value for _p_r__s_c_a_l_e is 0 or 1, and is rendered ineffective by giving a
  116.      _b_u_f_s_i_z of 0.  Profiling is turned off for the specified region of text
  117.      space if a _p_r__b_a_s_e update would cause a memory fault.
  118.  
  119.      Profiling is turned off when an eeeexxxxeeeecccc((((2222)))) is executed, but remains on in
  120.      both child and parent processes after a ffffoooorrrrkkkk((((2222)))) or a sssspppprrrroooocccc((((2222)))).... A call to
  121.      pppprrrrooooffffiiiillll((((2222)))) has the same effect as calling sssspppprrrrooooffffiiiillll with just one member in
  122.      the _p_r_o_f_p array with the fields _p_r_o_f_c_n_t, _t_v_p and _f_l_a_g_s taking on the
  123.      values of 1, NULL and PROF_USHORT respectively.
  124.  
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135. SSSSPPPPRRRROOOOFFFFIIIILLLL((((2222))))                                                          SSSSPPPPRRRROOOOFFFFIIIILLLL((((2222))))
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.                                                                         PPPPaaaaggggeeee 3333
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.